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Problem reports 

All reports of problems related to Spice or its documentation should be mailed to the ArpaNet address 
Spice@CMU-CS-Spice. r lliis address may be abbreviated to Spice@Spice on CMU Computer Science 
Department computers. To keep track of die latest changes in systems, documentation, and procedures, all 
Spice users should read the "Spice" bulletin board on any of die local host-machines. 

Where to find things 

All Spice software is currently stored on the CMU-CS-CFS Host (a Vax Unix) in a directory tree rooted at 

/usr/spicc. To get an up-to-date Spice system, including both the Accent kernel, the servers, die standard 

commands and utility programs, use the Update program, type 
path /Sys/Spice 

This places you in the proper directory. Now type one of the following, depending on your Purq's model: 
update PerqIA.CIO 
update PerqlA.OIO 
update Perq2 
update PerqT2 

See Appendix B to determine which type of Perq you are using. 

To get just one particular system, such as DP, you would type 
update dp 



• 



• 



• 
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Preface to the Second Edition 

The Second Edition to the Spice User's Manual represents the changes under the S5 version of the system. 
r lTie primary changes are 

• die new syntax for filenames and shell command lines 
the addition of access codes and an authorization server 
the coversion of BfndBoot, Scavenger and Partition to run under Accent 
the addition of a Bye command 

K. Eligator, Aug. 1984 
Preface to the First Edition 

This Introduction to the Spice User's Manual is based on a preliminary version written by Roger 
Dannenberg, Kathleen Ferraro, and Richard Gumpertz. Additional material for this first edition was 
provided by Bernd Bruegge and Mary Thompson. Robert Baron, Thomas Newton, and David Nason 
provided many comments and suggestions for improving this document 

Parts of the preliminary version were extracted from previous documents written by members of the Spice 
project or its industrial affiliate, Pcrq Systems Corporation. In this regard, we wish to thank: J. Eugene Ball, 
Miles Barel, Jeffrey L. Eppinger, Diana Connan Forgy, Brad A. Myers, David A. Nichols, Robert Sansom, 
Donald A. Scelza, Joyce H. Swancy, and Jon A. Webb 

In addition, we thank the entire Spice group for describing things to us and helping us track down details. 
The present and past members of the Spice project are listed in Appendix I. 

The intended audience for this Introductory User's Manual varies greatly in their knowledge about computers 
and computer usage. Some readers will be experienced programmers, others will be experienced users of 
computers without ever having to write programs, and finally, there will be readers for whom Spice is their 
first exposure to state-of-the-art computing. We make the assumption however, that the readers are familiar 
with, or can easily learn about the computing facilities of the CMU-CS Department: this document will not 
tell you what is a"Dovcr", or what does it mean to "send mail to Spice@Spice". These are items that belong 
in a more general CMU-CS Facilities Manual (there is one and it is updated periodically.) 

To help the less experienced readers, explanations and details that are of interest only to programmers or 
advanced users are presented in paragraphs with wider margins and in a smaller font. These can be safely 
skipped on a first (or Nth) reading. In addition, a glossary of commonly used "SpiceTalk" terms is given in 
Appendix A. 
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MRB, December 1983 
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1. Introduction and Organization of the User's Manual 

Spice stands for Scientific Personal Integrated Computing Environment. It is a project within the Computer 
Science Department of Carnegie-Mellon University with the goal of providing the software for a computing 
environment based on powerful personal computers. r lTic environment that results will be able to replace the 
current time-shared systems for the majority of the computing needs of the department, and it is expected that 
it will serve these needs into the 1990's. Hie project is now making a public release of S5 version software. 
Iliis software executes on Pcrq Systems Corporation Pl-RQ computers, which arc being used as interim 
development machines. 

This release represents significant steps toward our goal. It contains major improvements relative to earlier 
versions. In particular, there arc advancements in terms of performance and coherence, as well as new tools, 
such as Mint and Sapphire. Although new tools or improved versions of older tools will continue to be 
developed, die success of Spice depends largely on the community using these tools with sympathy but also 
with critical appraisal of their performance. 

The documentation for this version of Spice appears in two parts. The first, the Spice User's Manual describes 
Spice for new or casual users of the system. ITie second, The Spice Programmers' Manual, provides detailed 
in formation of interest p rimarily to p rogrammers. 

The Spice User's Manual is also divided into two parts: the first part, this Introduction to the Spice User's 
Manual, provides general information on Spice and its applications. The second part of the Spice User's 
Manual is a collection of manuals describing individual components of the system. 

After the Introduction and Overview of Spice, you will find three chapters describing the Prrq hardware, the 
file system naming conventions, and the Shell. They contain instructions on how to get started and document 
many of the quirks and miscellaneous details that are usually discovered the hard way. The next chapter 
contains brief descriptions of several commands and subsystems likely to be used by most members of the 
CMU CS community. These include, for example, document production facilities. Following, you will find a 
chapter describing problems that you might encounter, together with some suggested recovery procedures. 
The appendices at the end of the document contain information that you will find useful at different stages of 
your familiarization with the system. Some of these you might want to read right away (e.g. the Glossary in 
Appendix A), others you could ignore until after you have had some practice sessions with the system. 

The second and larger part of this Spice User's Manual consists of manuals, some of which were prepared 
specially for this release and some of which were already in existence. The manuals arc appended to the first 
part in the following order: 
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Users Guide to the Sapphire Window Manager 

Oil: The Spice Ascii Editor 

Hemlock User's Manual 

User Manual for Mint: The Spice Document Preparation System 

DP User's Manual 

Cousin User's Manual 

Mercury 

Update: A File Transfer Facility 

Spice Commands and Utilities 

The Spice Programmers' Manual contains the following documents: 

Systems Programmers' Manual 

Theory of Operations 

AccUnix - Accent Style IPC under UNIX 

Perq Pascal Fx tensions 

Pascal Library 

Accent Public Module Index 

Server Manual 

Matchmaker: The Accent Remote Procedural Call Language 

Procedural Interface to the Sapphire Window Manager 

User Manual for Kraut: The Spice Interim Debugger 

Sesame: The Spice File System 

Accent Kernel Interface Manual 

Cousin Application Builders Manual 

Mint Reference Manual 

Hemlock Command Implementor's Manual 

Spice Lisp User's Guide 

Device Utility Programs Manual 

The following documents arc also available: 

Perq C Programming 
Microprogrammed Reference 
Pascal/C Machine Reference 
Disk and FileSystem Data Structures 

2. Overview of Spice 

The kernel of the Spice operating system is called Accent. For historical reasons, the whole Spice operating 
system has come to be called "the Accent System," or simply "Accent." Thus, the name Accent refers to both 
the kernel and the operating system built around it Incidentally, there is another operating system installed 
on your Perq called POS. At CMU, POS is used as a back-up system. 

In many computer systems, the term "operating system" stands for some radier large, monolithic program 
which does most of the work. It reads and interprets command lines typed by the users, it manages and 
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protects files and directories, it provides network access facilities, etc. In Spice, the Accent kernel provides 
processes, address spaces, and message-passing primitives. Other services commonly thought of as being part 
of the "operating system" such as the file system, command interpreter (shell), network communication and 
screen management are provided by separate "server" processes which look like ordinary application or user 
programs. 

Accent is written in a combination of micro-code and Pascal. Unless you arc an advanced user, with special 
needs, you will rarely come in touch directly with Accent. Rather, you (and your programs) will interact with 
the servers built on top of die kernel. The server processes get the job done by executing "kernel calls" on 
your behalf. 

An Accent process Ls associated with a uniform virtual address space of 2 16-bit words. This address space cannot -be 
shared with another process, and even messages are passed by copying (although there arc some implementation tricks to 
make this efficient). As a result, a process is protected against corruption by other processes, thus preventing bugs in one 
process from mysteriously modifying the behavior of other processes. 

Accent is designed to support multiple instruction sets, so process state is defined in terms of the microcode interpreter. A 
process swap can occur at any point in the microcode execution designated as safe by the microcode implemcntor. On a 
process swap, Accent saves microcode registers: thus, a process swap can occur even in the middle of the execution of a 
macroinstruction. At present, microcode exists for Pascal and Lisp, and at least one project (DSN) has written application 
microcode to speed up their programs. 

Communication between processes is through "messages" sent to and received from "ports", using a 
machine-independent interprocess communication facility, named "IPC." IPC is the "glue" that holds 
together a system of otherwise independent processes. In Accent, process interaction is always explicit and 
always takes place through IPC, thus it is a simple matter to put communicating processes on separate 
machines. In particular, since all access to the screen and keyboard is also made through IPC, you can operate 
and debug a distributed system from a single console. We have taken several programs consisting of multiple 
processes, debugged them on a single machine, and then distributed them with few surprises. 

IPC is an asynchronous message-passing system with buffering, flow control, and protection mechanisms. The kernel 
maintains structures called ports to" which messages may be sent and from which messages may be received. Ports are 
referenced within a process by a local name. For convenience, the term port has come to mean the local name for a port as 
well as the kernel object To send or receive a message, a process must have "send" or "receive" rights for a port. These port 
rights are managed by the kernel and represent a form of "capability". like capabilities in other systems, port rights can be 
transferred within messages, and cannot be forged. This property provides the basis for a number of security mechanisms 
within the system. 

To make message passing efficient for large messages, Accent performs a "virtual copy" instead of moving data physically 
from one location to another. This is accomplished by manipulating address maps so that pages in two address spaces are 
mapped to the same physical page. The copy semantics are maintained, however, because any attempt to write into a shared 
page causes a page fault, at which time the page is physically copied. 
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2.1. Server Processes 

The Spice operating system consists of a collection of server processes in addition to the Accent kernel, These 
servers arc started automatically at system "boot" time. In this section, the function of each of the main server 
processes is summarized to give a global picture of the system structure. 

Sapphire manages the display, keyboard, and graphics tablet and serves two main purposes. First, it provides 
facilities to support graphics and text 10. Second, it protects the screen from uncontrolled access by the 
servers or user programs. Without this protection, any program could write arbitrarily into portions of the 
screen ("windows") allocated to other programs. Operating system servers, as well as user programs, 
communicate with Sapphire via IPC, although simple text 10 is often handled by the language 
implementations. 

Sesame is the Spice file system. Actually, Sesame consists of a collection of cooperating servers, which handle 
different aspects of the system: naming, file access, authorization and authentication, and migration. At 
present, only part of Sesame is implemented 1 , and each Pl-RQ is treated as a separate file system. Ultimately, 
Sesame will implement a global name space, spanning all the machines in the department, and allowing the 
protected sharing of files and named objects between various users. ITic system will also include automatic 
file migration to archival storage. At present, however, Sesame provides a simple form of network file access 
and limited protection. 

The Message Server is a process that extends the local IPC facility over the network. When a message is sent 
to a port on a remote machine, it actually goes to the local network server, which then forwards it to the 
remote network server over the cthernet The remote message server then sends the message as a local IPC 
message to its destination port. This whole process is transparent to the sender and receiver of the message in 
most respects. 

The Spice message server also allows a process to post a name for a port. Another process can then present 
the same name and obtain the right to send messages to the. port. The message server will use the network to 
search for remote ports if a local lookup fails. These functions are performed by a piece of the message server 
that is sometimes called the Message-Name Server; it is not really a separate server in the sense of being a 
separate process, although it is easier to think of the Message-Name server in these terms. " 

The Net Server provides packet-level access to the ethernet 



The interim version of Sesame goes by the name of "Sesamoid" although many people ignore this distinction and stick to "Sesame" 
We will ignore the distinction and hope you will not be confused. If you hear Sesamoid, think Sesame and you won't be too far afield. 
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The Environment Manager provides mechanisms to define new commands, to set default pathnames and 
search lists, and to define variables. These facilities constitute the environment in which the shell, servers, and 
user programs execute. 

Finally, we come to die Process Manager , a server that takes care of a number of tasks related to process 
creation and process termination. The Process Manager is also used to allocate display windows on behalf of 
Sapphire. 

2.2. Applications 

Although Spice is a new system, several substantial applications are already available. In this section, we 
survey the application programs available in the current Spice release, but we omit any discussion of file 
utilities and compilers at tliis point 

• There arc two Spice editors. The older, called Oil, is a screen editor in the style of RMACS. Oil is* 
- a simple editor, lacking the frills and extensibility of RMACS, but is otherwise quite comfortable 

and has been in use for a long time. A newer editor, Hemlock is a more faithful implementation of 
RMACS. 

• A drawing program, DP, is available to produce illustrations and technical drawings. DP has been 
used extensively for electronic circuit diagrams, and post processors are available to perform 
consistency checking and to generate wirelists from circuit diagrams. Illustrations generated by 
DP can be incorporated into documents produced by Mint, the Spice document preparation 
system. 

• Mint is a powerful system for document formatting and layout It incorporates multiple 
interpreters (currently a Scribe-like language, DP, and Plot), and will format output for either the 
Perq screen or die Dover printer. 

• Update, a version control and file transfer system, can be used to move sets of files between a 
Perq and a Vax Unix. Update provides the basic mechanism for distribution and updating of 
Spice software. You will find it very useful for maintaining your own software and document files. 

• Mercury is a mail system based on Rdmail. It is also available on Vax Unix under the name Hg. 

• In the area of programming tools there is, of course Pascal, the original language for the Perq and 
the implementation language for the Kernel and most of the servers, commands and utilities. In 
addition, SubAda, a compiler for a subset of Ada is available. SubAda is link-level compatible 
with the Pascal compiler and it can also be used on Vax Unix. 

• Spice Lisp is now running on Perqs. We expect to see large performance improvements and 
some application programs in the months to come. One of the first application programs is the 
Hemlock editor. 

• An IPC interface generator, called Matchmaker, a powerful debugger called Kraut, and a macro 
preprocessor, Pasmac, are also available. Matchmaker generates client/server interfaces that look 
like procedure calls. Most of the details of IPC message formats and system calls are thus hidden 
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from the programmer. Kraut is a symbolic debugger for Pascal and SubAda programs with a 
conditional tracing facility and the ability to display values in user-defined formats. Pasmac is a 
macro preprocessor which has been used to generate Pascal and microcode programs. 

• AC compiler and a Unix-like environment (Spoonix) arc also beginning to run on Phrqs: mis 
will make a large body of existing programs available on the Pf.RQ. 

• Cousin is a program that provides uniform, cooperative, graphical command interfaces to Spice 
applications. It implements a "form-filling ,, model of user interface and is intended to replace the 
variety of arbitrary command, parameter, or switch naming conventions that, for historical 
reasons, are currently in use. 

2.3. A Glimpse at the Future 

Before describing the present system in greater detail, it is worth mentioning some of die directions in which 
Spice is moving. This is not a complete list, nor is it a promise to actually implement anything. 

An algebraic programming environment for Ada, called Ada+, is also being developed. ITiis will integrate 
several aspects of programming environments within a single, coherent implementation. 

With new languages comes the problem of producing and maintaining multiple interfaces to servers. We are 
working on an interface specification language which is machine and language-independent and a new 
Matchmaker program to generate IPC interfaces for each language. 

While Mint is currently a non-interactive document formatter, its internal structure was designed to support 
interactive document design and incremental formatting. We expect to sec Mint evolve into an interactive 
system. In addition, there is interest in extending Mint to produce and format mathematical, Hindi, and 
musical notations. 

The present operating system offers very little security. Work is in progress to make network communication 
more secure through encryption and the use of a secure central authentication server. Mechanisms to provide 
protected resource sharing are also being implemented. 

Finally, a debugger for distributed, multiple language systems is being implemented. This debugger will be 
based on Kraut 

3. Getting Started • The Hardware 
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3.1.ThePERQ 

Spice software, including its operating system Accent, currently runs on the Perq Systems Corporation PliRQ 
personal computer. ITicre are three types of Perqs at CMU, PliRQ 1 A, Perq2, and PERQT2. 'Hie main 
hardware features and the differences between the models are described in Appendix B. 

On a not-too-dctailed inspection, Perqs share the following features: 

• high-resolution graphics using a 1024 x 768 bit-mapped raster display; 

• optional 1- Mbyte (double-sided, double-density) floppy drive; 

• internal (Winchester) disk; 

• Ethernet interface; 

• tablet and pointing device; 

• standard keyboard with special function keys; 

in addition, there are a few features of the Perq which may not be immediately obvious on inspection but 
which the user should know about: 

• The Boot button causes the Perq to restart its microcode. On the PerqIA, the boot button is 
located at the rear of the keyboard, just above the cable. On the Perq2, the boot button is in the 
bottom right side of the display cabinet, next to the keyboard cable plug. On the PERQT2 the boot 
(Reset) button is located on the front of the main processor cabinet. 

• The Diagnostic Display (DDS) is a three digit display which is set by the microcode to help 
maintainors diagnose problems. On most PERQ 1 As the DDS is located under the keyboard 
although in older models, it is hidden behind the front panel of the main processor cabinet. On 
the Perq2, it is located in the center of the base of the display cabinet. On the PerqT2 the DDS 
is located on the front of the main processor cabinet 

• The Brightness control for the screen is located on the back of the display cabinet. 

• The Volume control for the audio output is also located at the back of the display cabinet. 

• There are two types of display cabinets at CMU, portrait (vertical) and landscape (horizontal). 
Most PerqT2s at CMU have landscape display cabinets. PerqIAs come with an Angle 
Adjustment screw for adjusting the tilt of the display screen; it is located on the back of the display 
cabinet Perq2s and PerqT2s must be adjusted by manually tilting the display cabinet into the . 
desired position. 

• There arc two kinds of tablets. The larger ones have a Tablet Reset button, located on the right 
edge of the tablet, underneath the overhang. 

• A Power Connect light, which indicates that power is connected to the Perq, is located at the 
bottom rear of the main Perq cabinet. It should be on whenever the Perq is plugged in. 
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• The Power On/Off switch is located in the front panel of the main Pkrq cabinet. 
Section 3.3 on Booting Accent, explains how some of these features are used. 

3.2. The Tablet and Pointing Device 

Perqs are supplied with two kinds of tablet/pointing device combinations. The larger tablet comes with a 
four-button puck. The buttons on the puck are colored and arranged in a diamond (Sec figure below). The 
smaller tablet is supplied with a 3-button mouse. The buttons are arranged horizontally and are referred to as 
left, middle, and right. The left mouse button is equivalent to the white puck button; the middle mouse 
button is equivalent to the yellow puck button; the right mouse button is equivalent to the green puck button. 
There is no mouse button equivalent to the blue puck button. Although the puck and the mouse are quite 
different in appearance and in (internal) mode of operation, from now on we will use the term "mouse" to 
refer to either kind of pointing device. 
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The Perq can only read the position of the mouse when it is on the tablet That is, one may move the pointer 
large distances (on the screen) using successive small "wipes" with the mouse (on the tablet). It should be 
lifted well clear of the tablet between wipes. 



Presssing and releasing a button are two separate actions and different programs would do different things in 
response to such actions. In addition, their behavior might be affected by moving the mouse after pressing a 
button and before releasing it. Be sure you understand what is expected by the programs (when in doubt, 
experiment but save vour files first! ) Examples of these programs include Sapphire, the Shell, DP and, Oil. 
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3.3. Booting Accent 

In this section we describe the normal procedure to be followed in turning the Perq on and bringing up 
Accent. Most of the time the operation will proceed very smoothly and in two or tiirec minutes you should be 
able to use the machine. However, if the operation docs not proceed as scheduled, you might want to consult 
Appendix C for more information about the procedure, known problems, and corrective actions you might 
take. 

Assuming that the Perq is initially turned off, the following steps may be used to turn it on and bring up 
Accent: 

• Turn on the power by pushing the power on/off switch on the front panel of the main cabinet. 
You should hear the sound of the fans. 

• After a few minutes, during which the disk is coming up to full speed, the Perq should 
automatically "boot" itself. Some Perqs, however, do not seem to do so. In that case, push the 
small Boot button located at the rear of the keyboard (on Perq2s, the boot button is located on 
the lower right hand side of the display cabinet). Many people regularly push the button after 
turning on the power. 

• After the disk reaches full speed, some strange patterns will appear on the screen, lasting about 10 
seconds. At this point the boot micro-code decides what operating system to boot by examining 
which keys on the keyboard are depressed: 

o Pressing none of the keys is equivalent to pressing (lower case) "a", which boots the 
standard Spice operating system, Accent. 

o Pressing the "b" key boots the old Perq Operating System, POS, which is used at CMU as a 
backup system. 

o There may be some other key combinations for other "bootloads," but the average user 
need not be concerned with them. 

• One of the first tilings Accent does after booting is to set its clock. It sends out a message on the 
Ethernet asking for the time. If it gets a response, it sets the clock and continues. If it gets no 
response (perhaps because the Perq is not connected to the network), then it asks the user for the 
date and time roughly as follows (the exact wording might change in later releases of Accent), 

Found paging partition sys:paging 
Paging size = 10076 

Accent System S4, 'a* boot 
Starting Time Server... Done. 

Asking for time... no answer 3RCC 
No time server accessible. 
Enter time of day as DD-MMM-YY HH:MM:SS 

At this point the user should type an appropriate response, such as: 

Ol-Nov-83 14:04:00 this is a 24 hour clock 
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Typing just ri-turn (or entering a date or time in a wrong format) will cause Accent to ask you 
again. 

• Beware that, unless your Pkrq is not connected to the Hthcrnct, this failure to read the date and 
time might be a symptom of a problem with your machine or tine network. If it happens often, 
report the problem. In any event, uc sure the time you type is correct vi-c. as correct as your wrist 
watch... don't be fuzzy). If you type in the wrong time or worse yet, the wrong date, you might 
have problems later on. If you realize that you made a mistake, it is better to end the session 
(Section 6.9) and then reboot. 

• Accent will then start several server processes, and finally start Sapphire, the window manager 
program. 

3.4. The Display 

Once Sapphire is running, the first window to appear is a small "icons" window, at the bottom of die screen. 
It contains the Sapphire icons: small pictures of the Process Manager, the shell, and any windows created by 
the user. A few seconds later, a second window appears at the top of the screen. This is the Process Manager 
window and is used to display system information. 

During the booting sequence, the Process Manager window traces the start of two additional auxiliary network servers 
(MsRServcr and NcjSerycr). If you are not connected to the Ethernet or if you do not have runnable (.run) files for these 
servers, the operation will fail and you will be notified through the Process Manager window. These servers are not critical 
for local operations; you can still use most of the Spice software. If they are not running, you will not have transparent 
access to the network, although programs like CMUFI'P and Update may still work properly. 

Finally, a large window appears in the middle of the screen and then a pointer, represented as an arrow 
appears towards the middle of the window. This is the current listener window. A shell (command 
interpreter) will start running in this window, "listening" to commands from the keyboard or mouse. 

4. Getting Started - The Software 

After Sapphire is running and has created the three initial windows and the pointer, you will be asked to 
login. See section 6.1 for more information on logging in. At this point the Spice shell (command interpreter) 
is ready to accept command lines and execute them. However, before learning about the shell, you must learn 
and become comfortable with a few conventions used to specify directories and file names. 



• 



Appendix D describes the notation conventions used throughout this manual. At this point vou might want to 
read it and become familiar with the conventions. 
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4.1. Devices, Partitions, and Directories 

Files in Spice are named much like those in Unix 2 , using pathnames: a list of names separated with the 
character "/", terminating with a directory or file name. 

In contrast to most operating systems running on the time-shared facilities in the CS Department, currently, 
on a Pl ; .RQ you must be aware of the physical devices used to store your files. The typical Pl-RQ might have, in 
addition to the regular Winchester disk, a Floppy disk drive. ITius, when you specify a file name, you must 
start by indicating which device contains die file, in addition, the Pl-RQ Winchester disk is usually divided 
into several chunks of storage, called "partitions". When you specify a file name stored in the disk, you must 
also specify the name of the partition containing the file. 

The name sys is reserved for the Pi-:rq's Winchester disk. If you use the Mount command to mount a Hoppy disk, the new 
device will have a different name (e.g. floppy or XYZ.) 

Partitions are divided into directories and directories can be further divided into (sub)dircctories, etc. to any 
number of levels. If you arc familiar with the Unix file system, the organization of the Spice file system should 
look familiar, in particular, a partition behaves like a directory, and you can store fiies at the partition level, 
without having to go into the (optional) directories inside the partition. 

Partitions play a special role in the Perqs. Operating system kernels and servers are stored at the partition level. During the 
boot sequence, the Perq microcode looks at the key being pressed to select a version of the operating system. The device 
and partition names of these system files are stored in a fixed area of the disk (the disk "boot area") and that is how the 
microcode finds them. You can not just move (or rename) these files without letting the system know about the changes so 
that it can update the disk boot area. 

Having to specify a device name, followed by a partition name, followed by zero or more directory names, 
before you get to the actual file name is not very efficient Sesame, the Spice file system, provides defaults for 
most of the components in a complete file name and you won't have to worry too much about device names 
and only a little about partition names. Examples throughout this chapter should make all of this clear. 

4.2. PathNames 

A complete file name or pathname for short, corresponds to a path in a "tree" of devices, partitions, 
directories and files. The root of the tree is always a device name. There are two main kinds of pathnames: 
absolute pathnames which start with a leading "/" and relative pathnames (i.e. relative to the current 
directory) which start with a name. Absolute pathnames are explained in Section 4.2.4 while relative 
padmames are explained in Section 4.2.6. In addition, sometimes you will find pathnames that start with a 
name and a colon. These involve the concept of LogicalNames, explained in Section 4.2.2; they are a third 
kind of pathname. 



TJnix is a Registered Trademark of Bell Laboratories 
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Since a directory can contain-both files and other (sub)dircctorics, the Directory command lists the latter with 
trailing '*/" characters to tell diem apart 

Sesame follows die Unix convention of using the reserved name ".." for die parent directory. For example, 
the pathname M/B/C/D/../../K is equivalent to M7B/E. 

4.2.1. File Names and Extensions 

A filename in Spice is a sequence of letters, digits, underscores ("J'), periods ("."), hyphens ■("-"), and dollars 
("$"). An extension is the portion that appears at die end of a filename, following thclast period (if there is 
no period, the filename has no extension; this is often refcred to as having die "null" extension). In Sesame 
there is nothing special about extensions, altiiough certain conventions have been established (e.g. .cmd is 
used for command filename extensions). These conventions are described in Appendix E. 

In Sesame, a complete filename also includes a "version number" as part of the name. The version number of a file is 
specified by a ";" followed by number, after the file name, 
/Sys/User/f oo. bar#l 

This release of Spice software does not make use of the version numbers. 

A filename cannot exceed 25 characters. No special significance is attached to the characters in a filename or 
even to the capitalization of the letters. The latter is an important detail to keep in mind if you are used to the 
Unix conventions or if you intend to move files between your Perq and a Vax Unix. 

Name your files using whatever mnemonic system you prefer. However, whenever possible, do follow the 
conventions for file extensions. This will make your life easier and will prevent obscure bugs arising from 
programs that make (sometimes) unwarranted assumptions about your file names. 

4.2.2. Logical Names 

The syntax LogicalName: at the beginning of a pathname is used as a synonym for another, perhaps longer, 
pathname. That is, a LogicalName can be thought of as being replaced by another string of characters which 
is its expansion. This is useful for abbreviating pathnames or to hide details about precisely which device or 
partition is to be used. For example, the logical name boot: corresponds to die pardtion from which Accent 
was booted. If Accent was booted from /Sys/Spice/ (i.e. device Sys, partition Spice), then the name 
boot:LibPascal/Sapphire.pas is equivalent to /Sys/Spice/LibPascaI/Sapphire.pas. 

At present, the following logical names are defined when your Perq boots: 

current: the user's current working directory, as set by the Path command (Section 7.3.) 

default: the user's default search list for files, as set by the SctScarch command (Section 7,3,) 
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run: 



boot: 



dev: 



cfs: 

rem: 

remlib: 

rcmboot: 

dp: 

help: 

mint: 

slisp 

spoonix: 

native-c: 

libpascal: 

remlibpas: 



Search lists arc explained in Section 4.2.3. Note that the command SctScarch keeps 
current: at the head of default:. That is, by default the system looks first in the 
current working directory before looking somewhere else. 

the system's default search list for runnablc (.run) and command (.cmd) files. Search 
lists arc explained in Section 4.2.3. run: is initially (at boot time) set to currcnt:,boot:. 
'ITiat means that the file system will look first in the current working directory before 
looking in the boot partition. 

the partition from which Accent was booted. Normally, this is Spice -but can be 
changed by die user: typing alternative boot selection characters on the keyboard at 
boot time results in the booting of different operating systems (e.g. Accent or POS) 
or operating system versions (e.g. Accent S3 or Accent S4), and these could be stored 
in different partitions. 

the device from which Accent was booted. At present, tliis is the PERQ's local 
Winchester disk, whose device name is Sys (POS can also be booted from floppy 
disks; someday we might be able to do this for Accent. Another future possibility is 
to boot across the network, from a disk associated with another Pkrq). 

the Spice area on the CFS vax. (Note: you must be running Rcmdcf for this logical 
name to be valid. See the Commands and Utilities Manual for details of Remdef.) 

ITie two remote server PERQS, spicel and spice2, and the CFS vax. 

the directory rem:lib/ 

the directory rem:spice/ 

the directory remlib: dp/ 

the directory remboot:help/ 

the directory remlib: mint/ 

the directory remlib :slisp/ 

the directory remlib :spoonix/ 

the directory remlib :native-c/ 

the directory boot:libpascal/ 

the directory remlib:libpascal/ 



You can define new logical names using the Define command, and you can examine the list of currently 
defined logical names using the Show command (Section 7.3). 
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For example, the run: search list can be (rc)dcfincd by the Define command, as in 
Def run: default: ,/Sys/User/Util ities 

in which case, the system looks first in the default: search list before looking in the Utilities directory in the 

I Ici»r nsirfritinn If VV'H nt\t h\i\1e anvu/horo fy\crt Fi\r mnnikln / ••■•rat .\r ^.*mm*nA i ~™A\ f51~„ 

^^„. ^,«. ......,.*.». .,. VT-... <iw«. jvswn uu; "iiviv vuv iv/l luiliiuuil V.1U11/ Ul \~WillllIUIl«J ^.IIIIU/ II1CA. 

4.2.3. Search Lists 

A "search list" is a convenient way of specifying a lot of libraries (directories) containing flics and programs of 
general use. There arc two predefined search lists, known by the logical names default: and run: (Sec Section 
4.2.2.) 

The default: and run: search lists differ in the way their contents are specified: directories can be inserted into or removed 
from default: via the SctSearch command (Section 7.3), while any search list, including run:, can be set via the Define 
command (Section 7.3.) SctSearch exists mostly for compatibility with POS. 

Pascal programmers will want to add the library boot: LibPascal to their default: search list. LibPascal contains source files 
describing the interface to most servers and system utilities. Itiese interfaces arc created by MatchMakcr. thus allowing 
Pascal programs to send and receive IPC messages with a minimal amount of trouble. LibPascal is added to the search list 
by typing one of the following command lines to the shell: 

SetSearch boot:L1bPascal 

Define default: boot:LibPascal -After-1 

The remote logical names are defined but are not automatically included in the default: and run: search lists. 
These logical names allow the user to invoke application programs from the server PERQs and the CFS vax. 

Typing 

Dp: dp 

will find dp.run on one of the server machines. 

Searching for files is done automatically by the file system. That is, the system will always look through a list 
of alternative directories in the proper search list The user can control the scope of the search by adding or 
removing directory names from the search list with the command setsearch. The most restrictive case would 
be to have an "empty" search list. Sesame will then look only in the current working directory 

4.2.4. Absolute PathNames 

An absolute pathname begins with the character "/" and is used to specify a file or directory name, 

independently of the current working directory. Absolute pathnames have the following syntax: 
/ DeviceName/ PartitionName{ / name} 

That is, a device name, followed by a partition name, followed by or more directory names (the last one 
could be a filename). 
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4.2.5. Network PathNames 

Besides Sys, the name for the user's own PKRQ, the device name in an absolute pathname could be the name 
of another user's Pl-RQ. This provides a simple naming scheme for accessing files and executing programs 
stored elsewhere on the Ethernet However, a few minor requirements must be satisfied for this to work. 

• The other machine must be on, running Accent 

• ITie other user must allow external (world) access to her files. 

• You must know the other user's Phrq, partition, directory, and file names. Thjs facility is quite 
new and no conventions have been established; try asking the other user. 

The name by which your Phrq is known diroughout the network is defined in a file named SysName in the 
boot: partition (i.e. boot:SysName). You arc free to edit this file and write any name you wish in the first line 
of the file (the first time you use the Phrq, the file might not exist; you must create it with Oil or Hemlock.) 
Common sense would seem to suggest that you use your last name (if this is truly a personal machine), an 
office number (if this machine is shared with officemates), or even a project name. Do not use 
"Harry QBovick" or "Sys" for obvious reasons. 

The name stored in SysName is registered in the Network when you boot the machine. If you just changed it, 
the new name will not be known until you re-boot 

4.2.6. Relative PathNames 

As explained before, a relative pathname (i.e. a pathname that begins with a name instead of a "/") can be 
interpreted in two ways, depending on the context in which it is used. Thus, which file is referred to in a 
relative pathname is command or program dependent 

In the first interpretation, a relative pathname is considered to be prefixed by the logical name current:. Thus, 
a pathname like A/B is equivalent to current:A/B which in turn is equivalent to the absolute pathname 
/sys/User/Bovik/A/B if the current directory is /Sys/Uscr/Bovik/. 

In the second interpretation, a relative pathname is considered to be prefixed by the logical name default:. 
Thus, a pathname like A/B is equivalent to default:A/B. Directories in a search list are searched until the first 
match is found. If the search list default: included several pathnames (say, /Sys/Larry/, /Sys/Curly/, and 
/Sys/Moc/), then A/B stands for one of the following filenames /Sys/Larry/A/B, /Sys/Curly/A/B, and 
/Sys/Moe/A/B, depending of the order of the directories in default:. 

The directories in the default: search list are searched in order; once one or more file names are found in a directory, the 
search terminates. Thus you might not get a complete search of all the alternatives in all the directories in this search list 
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A command like delete assumes the first convention (this is a good precaution: if you make a mistake when 
typing the file name, the system won't accidentally delete a file in a different directory.) The Oil editor 
assumes the latter (editing the "wrong" file causes no harm, you can always leave the editor without altering 
the file.) Since default: includes current: as the first place to search, the second convention will look first for a 
match in the current working directory before trying for matches in other directories. 

Programs like ihc linker, would use the the second convention to find program modules but the output, a .run file, will 
appear in the current directory, even if all the modules came from a different directory. 

4.2.7. PathName Restrictions 

For the time being, only directories, files, and ports can be specified with a pathname. In the future, the same 
naming convention will be extended to include many other types of objects. 

The total length of any pathname must not exceed 255 characters although individual components of a 
pathname can be up to 80 characters long. 

Because upper- and lower-case letters arc considered distinct by the. Unix file system, some care with 
capitalization may be necessary when dealing with Unix. The simplest way to avoid problems is to use only 
lower-case letters when naming a file that might be stored on a Vax Unix system. 

4.2.8. Wildcards 

Special "wildcards" may be used when specifying pathnames to some (but not all) commands. This allows 
one to name several different files at one time. Typing a "*" as part of a pathname, matches or more 
characters in the place where the "*" appears. Typing "?" matches exactly one character. For instance, if a 
directory contains files abel, abcl2, abc2, wildcards could be used as follows: 

ab*l matches abel ; a one-character match. 

abc* matches all three files. 

abel* matches abel and abc 12. 

*bc*2 matches abcl2 and abc2. 

abc? matches abel and abc2. 

With the exception of the Directory command, wildcards may appear only in the last component of a 
pathname: 
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Delete A/B/* is legal 

Delete A/*/C is not legal 

Directory A/B/* is legal 

Directory A/*/C is legal 

For a more detailed discussion' of the file system, see Sesame: the Spice File System. 

5. Access Privileges 

A file is owned by the user who created it. ITic owner determines read privileges (permission to look at die 
file) and write privileges (permission to change the file). Read privileges include typing, copying, and 
executing. These privileges are set separately for others and the owner (for example, you might want to 
prevent yourself from accidentally deleting a very important file). 

The command to set access privileges is 

setprotect <directory or filename> 

followed by one or more non-conflicting switches: 
-Owner-Read (default) 

-OwnerWrite (default) 

-WorldRead (default) 

-WorldNoWrite (default) 

-OwnerNoRead 
-OwnerNoWri te 
-WorldNoRead 
-WorldWrite 

You may use wildcards in the directory or filename. 

The Read access privileges set for a directory apply to all the sub-directories and files in that directory. For 

example, suppose in the User partition you have several nested directories under the directory reports and the 

path to one of the files is as follows: 

/sys/usr/reports/prod/inv 

Read access is checked at every step in the path, so the read access privileges set for the reports directory 

would apply to the prod directory and the inv file, as well as the other files or directories nested under the 

reports directory. 

The Write access privileges set for a directory apply only to the files in that directory. For write access to the 
file inv, the user must have write access to the file and to the directory prod. 

To sec the access privileges for a directory, give the directory command with the -All or -Protect switch. This 
command may take a litde while because the authentication server that checks the access privileges runs on a 
remote perq. 
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If the authentication server is down or if you have not logged in, you will have complete access to your own 
files and world access to other user's files. 

6. Getting Started - The Shell 

lTie Spice shell is a fairly simple command interpreter. It prompts the user with a black-filled ">" and reads 
and executes command lines, one at a time. 

Because the various commands were implemented over a period of time with no explicit agreement upon 
conventions, users will encounter a number of different styles for interacting with programs. With time, we 
hope that some consistency will emerge through the use of facilities like the Cooperative User Interface 
(Cousin). This, and other standardizations, are strongly encouraged. Nevertheless, dierc have arisen .a few 
patterns of usage style that should be mentioned. 

Appendix D describes the notation conventions used throughout this manual. Before reading this chanter, 
vou should be familiar with the conventions. 

6.1. Logging In 

The login prompt will appear after the three initial shell are created in the boot sequence. The shell will 
prompt for a username and a password. The login authorization server runs on a remote Perq so that it may 
take a few minutes for the login to be confirmed. If you are not registered with the authorization or supply an 
incorrect password you will recieve an error message. Send mail to Spice@Spicc to be registered with the 
authorization Server. The login procedure is used for determining file access privileges (See section 5). 

6.2. Command Line Conventions 

The standard command line consists of the name of a command, followed by any number of "input" 

arguments separated by commas, followed by any number of "output" arguments, followed by "switches". 

Switches, which are used to specify desired variations in command behavior, usually start with a "-", and can 

take a value, as shown below, 

Edit MyTextFile.mss Invokes the Oil editor on a user's file 

SetSearch boot : LibPascal , /sys/user/w Adds two directories to the current search list 

Directory *.Pas >x Lists the names of all files with extension. pas into a fde named x 

Delete Test* -NoConfirm Deletes all files beginning with test, without asking for confirmation 

Link Modulel,Module2,Module3 ~ProgramName -Map 

Links several modules into one runnable program and produces a link map 
link test -StackSize = 1024 -Map Specification of a stack size 

That is, input arguments are separated by commas, as are output arguments. The two classes are separated 
from each other by a tilde, however, a comma or space can be used for some commands that expect only one 
input and one output. Spaces are permitted instead of the commas separating input arguments. 
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Formally, lhe command line syntax is as follows 

Command^SwitchList] ilnputArgUst] [~][OutputArgList'] ISwitchList] 

where both the Input ArgList and Output ArgList are of. the form: 

Argument[Swi(chUst2 {,Argument[SwitchList] } 

and a SwitchList is of the form: 

{■Switchl=Valuejy 

Sec Appendix D for a description of the conventions used to represent the syntax of commands. 

Most commands normally accept simple names as arguments. Sometimes, it may be necessary to specify an argument which 
includes characters that would be interpreted as delimiters (such as space, comma, or dash). To allow this, there is a 
"standard" (and unusual) quoting convention: precede the character with a backslash (/). For example, 
alias clean delete/ *.oil/,*$/ -noc 

represents a string that includes an space, a comma, and a slash. This convention is quite different from the Fortran, PL/I, 
or Pascal quoting convention of enclosing Lhe entire string in quotes. Furthermore, it makes no provision for specifying the 
zero-length (null) string. Note that many commands do not fully support this convention anyway. 

Most Spice commands and utilities either ignore the difference between upper- and lower-case characters or 

follow the rule that the original capitalization should be used when displaying a name but any combination of 

cases should be accepted when matching one name against another. For example, assume that we use the Oil 

editor to create a new file: 

Edit MyTextFile.mss 

After we finish editing the new file, its name will have the capitalization used above although the shell will 

accept the following alternatives: 

Type mytextf ile.mss 
Type MYTEXTFILE.MSS 
Type mYtEXTflLE.MSS 

In each case, the newly created file is typed on the screen. The directory command always spells filenames 
using the original capitalization. 

What constitutes a valid argument or switch is program- or command-dependent and you must consult the 

proper documents. Over time, a few conventions have arisen. For example, many commands would respond 

to the help switch by typing a short description of their operation, and the correct syntax to invoke them, as 

in: 

directory -help 

The help switch overrides all other switches. Notice that the switch is spelled out "h" "e" "1" "p" and should 
not be confused with the keyboard key labelled HELP. 
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Some programs, like Chat, use the nra.p key as a "help" command, to distinguish it from the word help being typed to 
another host machine. Chat commands are specified through combinations of special keyboard keys since it has no way of 
distinguishing between a command to Chat and a command with the same spelling but meant for the other machine. 

6.3. Special Command Lines 

If the command line starts with an "@'\ then the rest of the command line should be the name of a command 
(.cmd) file from which shell commands may be read. Command files may be nested arbitrarily but there is 
currently no facility for passing parameters to command files. Note that only lines containing shell 
commands, not lines read by application programs, may appear in a command file. 

If the command line starts with an "#", then the remainder of the line is treated as a comment and is ignored. 
This is especially useful to document command files. 

If the command line has an "&" appended, then the command will be executed in another process which runs in parallel 
with the shell and uses another window. The process manager will prompt the user to indicate the size and position of that 
window. This suffix is ignored if the command line begins with an "@". To run a command file in parallel, first create 
another window and then invoke the command file in that window's shell. 

The shell recognises special directives which are surrounded by "[" and "]". These directives control the manner in which 
the command will be executed. The directives are: - PARALLEL has the same meaning as an "&". - DEBUG executes the 
system debugger before your command. 1Tiat is, the kraut debugger will be invoked on the suspended child process. 
- LOADDEBUG displays loader debugging information. - SAMEENVPORT means that the child process should inherit 
the shell's port to the Environment Manager. 

Redirection commands similar to those in Unix may be used: ">" is used to redirect output, "<" is used to redirect input, 
and "J" is used to pipeline one program's output into another program's input 

A semi-colon ";" may be used for sequential process execution. 

6.4. Using the Spice Shell 

The shell looks for a command name (an arbitrary string of characters delimited by a space, " = ", or "-") at 
the beginning of the command line. The remainder of the line is saved for the program implementing the 
command. If the shell can find a runnable (.run) file with the same name as the command, then that file is 
executed. Otherwise, the shell checks whether the command name matches one of its built-in commands. 

Remember that .run files arc looked up in the run: search list, not in the default: search list. If you are not happy with having 
different search lists, you can always define run: to be equal to default: by including the following line in your profile 
(boot: LserProfile.cmd) file: 

def run: defau!t:-Global 

A list of the built-in commands may be obtained using the "?" command; individual commands are 
documented in the Spice Commands and Utilities Manual. Built-in command names can be abbreviated, 
provided there is no ambiguity with another built-in command. Thus, for instance, the SctSearch command 
could be typed as sets, the Directory command as dir, etc; 
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I"he shell supplies a default Tile name to several commands. For example, if you want to compile a program immediately 
after editing it. you can omit the file name from the Compile command. Commands that currently use or set this default file 
name are Edit. Compile, Link, and Run. In addition, the Type command uses this name as a default parameter but will not 
change the default. 

6.5. The Intra-line Editor 

The shell provides a facility to edit command lines as they are being entered, before typing REl'URN. By 
default, the editing commands arc modelled after the KMACS editor although the actions associated with die 
keys can be modified by the user (See Appendix H and the Procedural Interface to the Sapphire Window 
Manager). 

6.5.1. Command Line Editing Functions 

The functions understood by the intra-line editor (assuming the EMACS-like defaults) are given below. Note 
that capitalization is important 

CTRL a Move cursor left to the beginning of the line. 

CTRL b Move cursor left (back) one character. 

CTRL B Move cursor left (back) one word. 

CTRL d Delete the character to the right of the cursor. 

CTRL D Delete the word to the right of the cursor. 

CTRL e Move cursor right to the end of the line. 

CTRL f Move cursor right (forward) one character. 

CTRL F Move cursor right (forward) one word. 

BACKSPACE or CTRL h or DEL 

Delete the character to the left of the cursor. 

CTRL H Delete the word to the left of the cursor. 

TAB or CTRL i or CTRL I 

Insert spaces up to the next tab stop (spaced every eight characters from the left 
margin). 

CTRL k Delete characters to the right of the cursor, all the way to the end of the line. 

CTRL n Retrieves (from an internal command buffer) a previously typed command line. See 

Section 6.5.3, below for further details. 

CTRL p Retrieves (from an internal command buffer) a previously typed command line. See 

Section 6.5.3, below for further details. 
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CTRL t Transpose the two characters to the left of the cursor. 

CTRL v Displays the following windowful from the transcript buffer. See Section 6.6. 

CTRL V Displays the previous windowful from the transcript buffer. Sec Section 6.6. 

CTRL w Turns "wrap" mode on. That is, output lines that would be too wide for the current 

window width arc continued onto the next line, i.e. arc "wrapped" around. r ITic 
wrapping is not permanent; if the window width is changed, the lines are redisplayed 
as per the new width. See also CTRL W, below. 

CTRLW Turns "wrap" mode off. That is, output lines that arc too wide for the current 

window width arc truncated. This is not a permanent truncation; if the window width 
is changed, the lines arc redisplayed as per die new width. Sec also CTRL w, above. 

OOPS or CTRL u Delete characters to the left of the cursor, all the way to the beginning of the line. 

CTRL LF Enables "more-mode" to control scrolling. Sec Section 6.5.4, below. More-mode is 

disabled by default. 

CTRlA Disables "more-mode" to control scrolling. See Section 6.5.4, below. More-mode is 

disabled by defaulL 

LF Allow scrolling to continue. See Section 6.5.4, below. The command is ignored if 

output is not suspended by CTRL LF. 

INS or FSC Completes a partially specified filename. See Section 6.5.2, below for further details. 

CTRL ? List the file names that could match a partially specified filename. See Section 6.5.2, 

below for further details. 

6.5.2. Automatic FileName Completion 

The INS (ESC on Pf.rq2s) key is used to ask the shell to complete a filename which has been partially typed by 
the user. The shell examines the characters to the left of the cursor and searches for a filename that begins 
with that sequence. If a unique filename exists, the shell inserts the rest of die filename and moves the cursor 
to the right of the last character, as if the user had just typed the entire filename. 

If the cursor is in the middle of a name, it is as if the "wildcard" character "*" had been expanded. For 
instance, if the cursor is under the "a" in the middle of the filename "foar" when INS is typed, then "foar" will 
be expanded to "foo.bar" provided, of course, diat "foo.bar" is the only file name that could apply (see 
below.) 

If no filename with the given prefix exists or if the prefix is ambiguous (i.e. more than one filename matches 



Introduction to the Spice Users' Manual - 26 

the prefix), the screen "flashes" for an instant, to indicate a failure to complete the filename; type one or more 
characters before trying INS again, until the shell reacts by completing the filename. 

If in doubt about the possible candidate file names, type CTRL? to get a quick listing of the current 
candidates. CTRL? typed all by itself, at the beginning of a command line, will list all files in the current 
directory 3 . Typed after a partially specified filename, CTRL? will list all filenames that could complete it (if no 
candidate filenames arc found, the screen will flash, to indicate a search failure). 

6.5.3. Retrieving Previous Command Lines 

ITie ctri. p and CTRL n commands are used to retrieve previous command lines. Previously typed command 
lines arc kept in a "ring" and the user can move around the ring, typing CTRL p to move backwards or CTRL n 
to move forwards. The old command line appears on the screen, with the cursor positioned to the right, as if 
the user had just typed it in. Sixteen commands lines are stored. 

Successive CTRL p or CTRL n commands can be typed until the desired line is retrieved. It can then be edited, 
if necessary. Typing return terminates the editing and the command line is then interpreted by the shell. 
Notice that the cursor does not have to be at the end of the line in order to type RirrURN 

6.5.4. Scroll Control a.k.a. "more-mode 55 

The shell has the ability to suspend output to a window if it would cause information to scroll off die top of 
that window. This is analogous to the terminal pause (ON) end-of-page feature in the TOPS-20 system, or 
"more-mode" in the Vax Unix systems. 

To enable this facility, type CTRL LF, as a shell command, at any time during the session. From then on, 
whenever the shell notices that output is about to scroll off the top of the window, it stops and displays die last 
line in the window in reverse video (white letters over black background). Typing LF allows output to 
continue. 

Typing anything other than a Sapphire Ctrl del command, will cause scrolling to continue. However, whatever was typed is 
saved and used as input the next time the shell or the program doing the typing wants to read something from the keyboard. 

Do not get into the habit of typing return when you mean if. How would you like to see the following prompt from a 
program, right after you resume scrolling with return? 
Delete ALL your files [Yes]?: 

To disable the scroll control facility, type CTRL \ as a shell command. This is the default mode after booting 
Accent 



If the current directory is empty, this command displays all the filenames in the first non-empty directory in the default: search list 
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If you forgot to set "more-mode" and some important program output scrolled off the window, you might 
still be able to read some of it by retrieving the previous transcript bufTer(s). Sec Section 6.6, below. 

6.6. Session Transcript Buffers 

ITic shell keeps a transcript of the session (i.e. user command lines and program output that appeared on a 
window) in an internal buffer. One can peruse this buffer by typing CTRL V and CTRL v to move backwards 
and forwards, one windowful at a time. 

The buffer keeps about three window fuls of text, thus the size of the window determines how much is 
retained in the buffer. Changing the size of the window, alters the size of the buffer for the remainder of the 
session (or until the next window size change). 

The transcript buffer does not behave like the command line buffers mentioned in Section 6.5.3. It can not be 
used to "replay" a portion of session or to retrieve previous commands. Typing anything, while displaying 
some previous portion of the transcript, simply advances to the end of the transcript and inserts the user input 
at the place were the cursor was positioned before the user started redisplaying the session transcript 

6.7. Creating Additional Windows 

There are several ways to create, move, and reshape windows. Sapphire provides complete sets of keyboard 
commands, pop-up menus, and mouse button commands to perform these and other operations. For detailed 
information on the creation and use of windows, see User's Guide to the Sapphire Window Manager. In this 
section we only describe the use of the Shell command. 

To create an additional window, type 
shell 

A blinking cursor in the form of an uppcr-left-corner will appear on the screen. Position the cursor where you 
want the upper left corner of the new window. Press and release any, button. The cursor will change to a 
lower-right-corner with an arrow. Move the cursor to where you want the lower right corner of the new 
window. Press and release any. button. 

In order to communicate with the new window, you have to designate it as die current listener. To do this, 
move the cursor into the window and press any button. When the button is released, the border changes from 
black to gray to indicate that the newly selected window is now the current listener. 

The current listener does not change by simply moving the cursor to another window. If one forgets to press 
and release a button, any characters (including commands) typed are sent to the last window designated as 
listener. Caveat emptor. 
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You can specify the first command to be executed by the new shell directly in the shell command: 
shell ShellCommandLine 

If a command is specified, it will be executed as soon as the new window is opened. Under some 
circumstances (e.g.- starting a server or some other process that does not require further interaction), the new 
shell is needed to execute exactly one command and you can use the following format: 
shell -quit ShellCommandLine 

if the - quit switch is specified, die new window will be eradicated (i.e. removed from the screen) as soon as 
the specified command is executed. ITic - quit switch must precede the command. 

'ITie process of creating a new shell from an existing shell is often referred to as "spawning". Spawned shells 
inherit a copy of the "environment" of the shell from which they were created. This includes things such as 
the definitions of current: (the current working directory) and default: (the current search list). 

6.8. Initial Command Files and User Profiles 

TVia Qnirr* chilli nrnviH^c fi\r fic**r nictr^mr/citintl vin mmmnnd filpc Aff^r HnnHno fh/» choll Irwilro f!r\r a filr* 

with the name InitialShell.Cmd in the boot: partition and then executes the commands contained in that file. 
InitialShcll.Cmd runs the command files, SysProfile and SitcProfile. These command files define new 
commands and environment variables, set server priorities, and define logical names. InitialShell.Cmd then 
runs UserProfile.Cmd which may contain user commands such as launch and user definitions. 

Creating a new window with the pop-up menu "shell" command or the keyboard ctrldels command, invokes the 
execution of two command files: boot:ShcllProfile.Cmd and boot:ShellConimands.Cmd on the new shell, if these command 
files exist, and in that order. The new shell inherits the environment of the initial shelL 

Beware that creating a new window with the shell command does not invoke any automatic execution of command files. 

6.9. Ending a session 

To terminate a session type the command Bye to the shell. This command invokes the Accent kernel 
debugger; wait until the debugger prompts with the character ">" for a command and then turn your Perq 
off. It is not possible to return to the Shell by typing "q" to the debugger because the partition has been 
dismounted by that point and cannot be remounted. You must either boot your Pfrq or turn it off. 

The kernel debugger is a rather sinister looking character; it shares Darth Vader's taste in clothing, and announces its 
presence by writing over a blacked out portion of the screen, disregarding window boundaries. Grown-ups have been 

known to cry over the debugger's blood curling battle cry: "106", "106" Sometimes it will cry "144", thus tricking you 

into believing that it is actually beginning to like you and that it might even recover..... fear not, eventually you will get your 
"106". 



Introduction to the Spice Users' Manual - 29 

7. Basic Commands and Application Programs 

Appendix D describes the notation conventions used throughout this manual. 

7.1. On-line Help 

'ITic help command provides explanatory text related to a command provided as an argument by the user: 
Help command 

If the Help command is typed without an argument, the user will be told about the Help facility and how to 

use it. If a command is supplied as an argument, any information available on that command is displayed. 
Help oil 

will print information about the oil editor. 

In addition, some commands and application programs recognize the help switch. If the help command 

describes above does not provide the needed information, try the following: 
name -help 

The "T' command lists the built-in shell commands followed by the user defined commands. 

7.2. Cooperative User Interface 

The Cousin server can be used to implement uniform, "form- filling" user-program interfaces. Any user 
program can become a "Cousin-application" by providing to this server information describing the "form" 
used by the program and communicating with the user through this form, using Cousin as a mediator. When 
the user starts the execution of die application program, the server is invoked and it displays on the screen the 
appropriate, application-specific form to be filled. The user types parameters, switches, commands, etc. in the 
appropriate slots in the form (very much like typing a memorandum or filling an income-tax return form, 
without the lattcr's noxious side effects). Cousin takes care of verifying that the data contained in the slots is 
complete or consistent before passing it to the application program proper. 

The application also uses the form to type information back to the user by passing these data to the Cousin 
server. The server then displays the program output in the proper format, as specified in the form description. 

For additional details on interacting with a Cousin based application, see the Cousin Users Manual in the 
Spice Users Manual. If you wish to construct a Cousin interface to one of your own application programs, you 
must consult the Cousin Application Builders Manual in the Spice Programmers Manual. 
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7.3. File and Environment Manipulation Commands 

7.3.1. Directory 

This command lists all file names in die current directory. To obtain a list of .run files, type 
dir *.run 

File names in other directories can be obtained by specifying the name of the. directory, including wildcards, 

if necessary: 

dir Use rU til ities :RunFiles/*. run 

The shell intra-linc ediliong command ctri.? , when typed a: the beginning of a command line, can be used to get a quick 
listing of the current directory. It is faster than Dir but does not have the complete functionality of the regular command: 
you can not specify switches, pathnames, wildcards, etc. If the current directory is empty, this command lists the contents of 
boot:. 

7.3.2. Path 

This command changes the current directory. If you type 
path 

and the current directory is /Sys/Spice the following message will appear on the screen: 
Old path = /Sys/Spice/ 
New default path: (CR to exit) 

If you do not want to change the current directory, type RETURN. If you to want to change to a different 

directory, for example, ../new, type 
. ./new/ 

You can type the new path name in the same line with the command, as in 
path ../new/ 

in which case you will not be prompted for a confirmation. "Path x" is equivalent to "Define current: x", 
where "x" is a valid pathname. 

7.3.3. MakeDirectory 

This command is used to create new directories: 
M a k e D i r NewDirectoryName 

For instance, to create a (subdirectory named foo inside the current working directory, type 
MakeDir foo 
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7.3.4. Copy 

r Hiis command is used to make copies of files: 
Copy OldFileName NewFileName 
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copy bar /sys/user/more 

copy /Rashid2/Spice/User/Peta1 .pas MyPetal.Pas 

The last example shows how to obtain a copy of a file from another Phrq on the HtherNct (i.e. from device 
Rashid2, partition Spice, directory User, file Pctal.pas) 

The OldFileName can have wild cards in it as long as the NewFileName has the same wild cards, in die same 
order. All files that match the source will be copied by taking die characters diat match each wild card and 
putting these characters in the corresponding place in the destination. 

7.3.5. Rename 

This command is used to change the name of an existing file: 
Rename OldFileName NewFileName 

For instance, to change the name of bar to more, type 
rename ban more 

die old file bar does not exist anymore. 

Renaming only works if the two filenames are in the same partition. To achieve the effect of Rename across 
partition boundaries, you would need to do a copy to the destination partition (OldFileName -> 
NewFileName), followed by a delete in the original partition. 

7.3.6. Delete 

This command deletes files. To delete a file say, test.pas from the current directory, type 
delete SomeFileName 

Delete irrevocably destroys the specified file (there is no undelete command). If you use wildcard characters 
in the specification of a file to be deleted, the command will prompt you for confirmation on each possible 
file. 



Introduction to the Spice Users' Manual - 32 

7.3.7. Show 

This command displays the environment variables and their values. See the Define and Alias commands, 

below, 

7.3.8. Define 

This command is used to define (or redefine) a variable in the environment: 
Define VariableName Variable Value 

where VariableName is of the form foo or bar: (the latter defines a logical name which can then be substituted 
in pathnames). 

To remove a variable from the environment, type 
Define VariableName 

that is, define it with the "empty" value. 

The VariableValue can be followed by the switches -local or -global. The -local switch makes the variable 
visible only to this shell and to shells spawned from it (creation or "spawning" of new shells is explained in 
section 6.7). The -global switch makes the variable visible to all shells. The default is -local. 

7.3.9. Alias 

This command is used to define new commands in the environment, e.g., 
Alias CommandName CorrimandValue Documentation 

where CommandValue is some previously defined command or program name (including arguments or 
switches). Typing CommandName as a command is equivalent to typing CommandValue 

Documentation is any information to appear with the command when you type "?". The documentation must 
be enclosed in quotes if it contains any special characters, including spaces. 

This substitution does not include the RETURN normally issued at the end of a command line, thus one could 

type the following 

CommandName FurtherArgumenlsOrSwitches RETURN 

as a command line. 
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7.3.10. SctSearch 

To add pathnames to the default: search list, type 
SetSearch PathName PathName 

SctSearch treats the default: search list like a stack: the last pathname added goes to the head of the list and is 

the first directory to try in a search. If instead of a pathname, you type the switch "-Pop" the pathname at the 

head of die list is removed from the search list. Alternatively, you can type just the command name: 
SetSearch 

Hie shell displays the current contents of the search list and prompts the user for input If a pathname is 
typed, it will be added to the front of the default: search list, if "-Pop" is typed, the first name in the list is 
deleted. Typing RirrURN causes the program to exit with no further changes. 

7.4. Producing Documents 

Spice provides tools for creating, editing, formatting, and printing documents and drawings. 

7.4.1. Oil 

To invoke Oil, one of the Spice editors, type 
Edit SomeFileName 

Oil commands are similar in style to those in Emacs. For more information see Oil: The Spice Ascii Editor. 

7.4.2. Mint 

To invoke Mint, the Spice document formatter, type 
Mint 

Mint will prompt you for the information it needs. Mint formats documents for the Dover printer or the 
Phrq screen. Mint commands are similar to those in Scribe. For more information see User Manual for 
Mint: The Spice Document Preparation System. 

7.4.3. DP 

To invoke DP, die Spice drawing program, type 
DP 

DP allows users to create illustrations and circuit diagrams. DP can produce output for the Dover printer 
directly or in conjunction with Mint. For more information see the DP User's Manual. 

To modify an already existing illustration, you can type 
DP SomeFileName 
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7.4.4. Dover 



ITie Dover program sends documents created on the Perq to the Dover for printing. It is invoked with 
Dover 

There are many switches available to enable you to specify where to ship files and how to format them. Type 
Dover -help for a complete list of switches. 

You can also provide the name of the file to be printed in the same command line, 
Dover SomeFileName 

7.5. Using the Ethernet 

Phrqs at CMU arc connected to die Rthernet. You may use your Perq as a terminal to connect to another 
machine on the Ethernet, to send and receive mail, and to transfer files. 

7.5.1. Chat 

The Chat program allows you to use your Perq as a terminal connected to another Ethernet machine. Chat 

simulates an HDS Concept terminal. If you type just, the name of the program, 
Chat 

You will be prompted for the remote host name. When you have established a connection with the remote 
host, simply log in as you would from any terminal. Type the help key for help and a list of commands (e.g. 
how to quit chat). 

If you type a host name in the same command line, 
Chat e 

Chat will not prompt you for a host name and will connect you to the "e" host. 

7.5.2. Cmuftp 

The Cmuftp program is used for general purpose file transfers between your Perq and any host machine on 

the EtherNet. Cmuftp will prompt you for additional commands with the character '*>". Type help for a list of 
commands and further explanation. 

7.5.3. Update 

The Update program is used to transfer files between the Perqs and the Vax systems. Update is the main 
vehicle for distributing Spice software and it has some built-in knowledge about the CMU-CS-Spice and 
CMU-CS-CFS Vaxen (these are the machines where Spice software is developed and stored). Of course, you 
can use this program and any other Vax Unix system on the Ethernet to maintain your own software and 
documents. Update is described in Update: The Spice File Transfer Facility. 
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7.5.4. Mercury 

Mercury is the Spice mail program. Its commands are similar to those in RdMail on the TOPS-10 systems or 

Hg on the Vax Unix systems. For more information, see the Mercury User's Guide supplied with this 

manual. 

Listing Mercury as an ethernet "user" is not quite correct. Mercury proper only deals with your local mailbox; 
it allows you to read mail messages and to write messages to be mailed. Mercury relies on an auxiliary server 
(MailMan) to do the actual transmission of messages over the Ethernet. MailMan normally runs in the 
background and its operation should be transparent to most users. 

8. What To Do When Something Goes Wrong? 

8.1. Reporting Problems 

The primary error-reporting mechanism is mail sent to "Spicc@CMU-CS-Spice" describing the problem. 

For some serious problems, there is specific information that you can collect and can be useful when trying to 
diagnose the problem: 

8. J. I. Failure to Boot 

If the Perq does not boot properly, please report the number displayed in the Diagnostic Display (DDS) 
(normally located on the underside of the keyboard on PerqIs and PerqIAs; it is located on the front panel 
of the screen cabinet on Perq2s). 

8.1.2. Accent Crashes 

An Accent kernel crash is normally indicated by entering the kernel debugger which types out white 
characters on a black background, ignoring Sapphire windows. 

Together with an error number, the kernel debugger sometimes will write a short message identifying the 
source of die problem. One problem you might find is described as "Running out of paging space". This 
happens when the paging partition used by Accent to support the virtual memory is exhausted; this could be 
due to having allocated too little space to the partition or after many hours of work, when many process and 
file pages have been "paged out". Rebooting the system will normally solve the problem. Other, more serious 
problems, are reported as "Illegal Memory Reference" (error 106) or "Uncaught Exception" (error 144). 

The kernel debugger has a primitive command language. Sometimes the system is able to recover from the 
crash and typing the command q will let you continue interacting with the shell. If the condition persists, your 
only recourse is rebooting. 
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It would be very helpful to the maintainors if you could report the message printed on entering the debugger plus the 
information printed out by the commands "c", "s". and T. For the T' command, the first few lines of output are 
sufficient 

8.1.3. Failure to Run 

Sometimes, when trying to run a previously linked program (i.e. a run file) you might sec error messages of 

the form: 

ALoad: Incorrect length for run file /sys/spice/LibPascallnit.RUN; 1 
Shell: Error in spawning /sys/user/guest/CALC.Run; 1 Code is 124 

Where the command you tried to execute (i.e. the program you tried to run) was calc.run. This error occurs 
whenever the program and LibPascallnit.Run (a system program normally linked with most Pascal programs) 
are inconsistent. In other words the program was not linked with the current LibPascallnit.Run 

This is not a serious problem (all that happens is that the program fails to be loaded and executed; thus the 
two error messages). To solve the problem you must relink the run file (i.e. calc.run in the example). If the 
seg (object code) files produced by the Pascal compiler are around (e.g. this is one of your own programs), just 
issue the same Link command that you used the first time you linked the program and you will have a 
compatible run file. 

If you do not have the scg files around, which is common if this is a library program or if you got it from some 

other user, then the link command to use is: 
link -relink calc 

This error is likely to occur if you brought to your Pl-RQ (say, via update) a new version of LibPascallnitRun 
and you already had Calc.Run or if you brought a (new) version of Calc.Run that was linked with a different 
version of LibPascallnitRun 

Sometimes, if this problem happens too often with programs you retrieve over the network, you might want 
to get (via update) a new version of LibPascallnit.Run; chances are you have an obsolete version. 

8.2. Getting Out of the Kraut Debugger 

Kraut is the name of the debugging program. Kraut will be invoked whenever an error is detected by the 
system (by the Process Manager, to be precise). If the error occurred in some system program it is unlikely 
that you will be able to do much debugging. You probably want to get out of Kraut, and back into the shell. 

When the Process Manager invokes Kraut, the Process Manager window. will change to reverse video (white 
letters on black background). A message stating the nature of the error (e.g., "uncaught exception") will 
appear, and the Sapphire cursor will prompt for the creation of a window (See Section 6.7). Once Kraut is 
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running in the window that you have just created, it will display some information regarding the status of the 
program when the problem occurred. This is information of interest to programmers and maintainers. After 
this is done, Kraut will prompt for debugging commands with the character "|". 

iO exit Kraut, make the new window the listener (move the cursor to the window and press and then release 
any mouse button; the border should change from black to gray) and then type the command Quit. 

If you want to report the bug to somebody (e.g. the program maintainor), type the command Calls, followed by the 
command Report, followed by the command Quit. Kraut will ask you for the mailing address of the intended recipient, your 
name, and whether you want to provide an additional message or not. If you decide to provide this extra information. Kraut 
will read lines of text, until you type a line that consists of just a period (".") in the first column. At this point. Kraut will 
package all the information and mail it to the specified destination, before terminating the debugging session. 

You should now make the original window the listener; do this before you type any shell commands. 

For on-line help about Kraut, type the command line Help or hit the help key while still in the debugger 
window. For more information see User Manual for Kraut: The Spice Interim Debugger. 

8.3. Partition and Scavenger 

These two programs are used to fix problems with the disk. Scavenger is rather harmless and is used to 
recover the "free list" of a partition. The free list is a mechanism used by the file system to keep track of the 
free space in each partition (except for the paging partition, which is never used to store files and therefore 
does not have a free list). Sometimes, a system error will cause the free list to be clobbered. This causes no end 
of grief to the file system (it can not create or delete files; often it can not even look at filenames inside a 
directory). Normally, you do not want to do anything with that partition: things can get really ugly otherwise. 
When the file system suggests that you "scavenge" a partition, do it 

On occasion, Accent will write on the screen a one line message of the form "Scavenging 3745623000". The 
message would appear in reverse video (white letters on black background), towards the top of the screen, 
ignoring window boundaries. This is not the message "suggesting" that you scavenge a partition. The latter 
will appear in normal video and will follow some file system action (e.g. after deleting a file, when leaving the 
editor, etc.). 

To run Scavenger, type 
Scavenger 

Scavenger will prompt for some parameters. Until you become an expert, follow its lead and use the defaults 
it suggests. Finally, the program will ask you for the name of the partition to be scavenged. Type the partition 
name and let the program do its thing. After reading the disk blocks allocated to the faulty partition, 
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Scavenger will try to reconstruct the files and the free list. If it finds some anomaly (e.g. a "broken" file) it will 
tell you. Sometimes it will ask you for information (e.g. a "file name") or confirmation (e.g. to fix an error in a 
"bad" file). Do what it suggests or ask an expert for help. 

Files are stored in the Pi-rq's disk as double- linked lists of blocks (512 bytes per block). An extra block is allocated as a "file 
header" and contains information about dates of creation and access, the name of the parent directory, the file length, etc. 
Although the usual reason for using this program is to recover the free list, the program is also useful to fix other problems, 
such as rebuilding split files and reconstructing directories that were accidentally deleted (the files are still there but not 
accessible). 

Partition is a heavy duty "fix-it-uppcr". Although it provides some functions that you think you would like to 
invoke (e.g. splitting or renaming a partition), it can also do more amusing tilings, like deleting the whole disk 
in just as many keystrokes. Do not use it until you know what you are doing. 

8.4. When Things Look Hopeless 

Reboot. 

However, to be safe, you should do so at some point when there is no danger of stopping the system while 
some disk input/output operation is in progress. If the shell is still capable of prompting for and executing 
commands, the safest way is to type the command Bye to the shell. This command invokes the Accent kernel 
debugger; wait until die debugger prompts with the character ">" for a command and then reboot 

If you can not type shell commands, then it is a good idea to wait for a period of time (something in the order 
of a minute), until no lights on the right-hand side, at the top of the screen, are flickering. This ensures that 
there is no disk activity. It is then safe to reboot. 
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Appendix A 
SpiceTalk Glossary 



his Appendix describes some terms commonly used when describing Spice facilities, 
Term Description 

Address space Instructions in a program refer to data and other instructions through their memory 
addresses. The address space of a program is the set of memory addresses that can be 
read from or stored into. Sec Virtual Memory. 

Boot, Booting In Spice, this word is used in two ways. First there is the action of "booting" or 
starting Accent and associated servers after the machine is turned on. On some 
Pr.RQs, booting docs not happen automatically after power is turned on: the "boot" 
button must be pressed and released to get the machine going. The second use of the 
word is in boot:, tine logical name for the initial partition i.e. the partition acting as 
the current directory right after booting the machine. 

Current directory Sec Directory. 



Current listener 



Cursor 



Device name 



Directory 



Environment 



Free List 



The current listener is the window/shell combination that is "listening to" (i.e. 
reading input from) the user's keyboard input The window is identified by having a 
thick, gray border instead of the normal thin, black border. 

Cursors are the small pictures used to "point" or select items on the screen. Typical 
cursors have simple shapes like arrows, underbars, etc. The undcrbar used by the 
intra-line editor to mark the current input position is also called a cursor. 

In the Sesame file naming convention, filenames arc specified as a sequence of 
(nested) directories names. The top level "directory name" (i.e. the first element in 
the sequence) is the name of the device where the file is stored. The device name can 
refer to a local device (e.g. Sys, the name for the local disk, inside the PL-RQ main 
cabinet) or to a device somewhere else on the network (e.g. Rashid could be the name 
of the local disk in the machine owned by user Rashid). 

Directories provide a convenient way to group related files. There could be many 
reasons to put a file in a given directory (e.g., program files related to one project 
manuscript files for a book, utility programs used in several projects, etc.) Directories 
can be nested, and a sequence of directory names, prefixed with a device name and a 
partition name, provides a unique path to a file. 

The set of logical names, search lists, user defined commands and variables, etc. 
available to the shell (and user programs). 

The Sesame file system keeps track of the disk space available to store files. The 
space is organized in blocks, 512 bytes long each. The free list is simply the list of all 
the currently available (i.e. free) blocks of storage that Sesame can use for a new file. 
Files themselves are also organized as lists of blocks. After removing a block from the 
free list the newly allocated block can be written into and then linked with the file's 
list of blocks. 
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Icon 



Icons are small pictures representing all -of the existing windows, including those that 
are covered by. other windows. Icons are displayed in the icons window, at the 
bottom of the screen. The icon corresponding to the current listener has a thick, gray 
border instead of the normal thin, black border. 



IPC, Inter-Process Communication 

The mechanism used to communicate between processes. Processes send or receive 
messages via ports which act as protected mailboxes. 



Kernel, Kernel Call 



Logical name 



A low-level machine operation, used- to request Accent to do something. For 
instance, to send a newly created message, to allocate more memory to a process, etc. 
Kernel calls are similar to "supervisor" or "monitor" calls in other operating systems. 

A logical name is just an abbreviation used to shorten a complete pathname or to 
hide details such as device or partition names. 



Message, Message passing 

Messages are the pieces of information (e.g. data, commands, etc) passed between 
processes. See IPC. 

More-mode The ability to suspend output being sent to a window after sufficient lines has been 

printed to fill the window. This gives the user a chance to read it before it goes away. 
After reading the information, the user can resume output for another window full. 

Mouse The mouse or puck is the device that slides on top of the tablet. Moving the mouse 

or pressing and releasing its buttons are meaningful actions to Sapphire, the servers, 
and user programs. The position of the mouse over the tablet is often associated with 
the position of the cursor on the screen. Thus, moving the mouse on the tablet 
usually changes the position of the cursor on the screen. 

Path name A path name is a complete specification of a file name, starting with a device name 

• (which could be somewhere else on the network), followed by a partition name, 
followed by zero or more directory names, followed by the actual file name. 



Paging partition See Partition. 



Partition 



The local Perq disks are divided into several large chunks of storage called 
partitions. In a pathname, the name of the partition containing the file appears after 
the name of the device, but before any directories inside the partition. There is a 
utility program, called Partition, which is used to initialize, split, rename, or merge 
partitions. 

paging is a special partition set aside in the local disk to help Accent implement the 
virtual memory of the servers and user processes. It is never used to store files. 

Spice is the default name for the partition containing all the Accent and server files. 
The logical name boot: stands for the actual partition name (you could be booting an 
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experimental system, residing in a different partition in which case boot: would be 
something other than Spice) 

Port Accent's version of a mailbox. Processes send messages to and receive messages from 

other processes via ports allocated and protected by Accent. Sec IPC. 

Process A process is the basic computation unit under Accent. Any number of processes can 

be running simultaneously, but their address spaces arc separate to avoid interference 
between them. Cooperating processes communicate via messages and ports. 

Puck Sec Mouse. 

Scavenging The operation of examining the disk, checking the integrity of the frce*list and the 

files. Often used to recover from file system errors that cause the free list to be 
clobbered or a file to be truncated. 



Scroll control 
Search List 

Server 
Shell 



Sec More-mode. 

An ordered collection of directory names, used by the file system to look for files 
when they are not found in the current working directory. 

Servers arc the processes that complement the facilities provided by Accent to make 
up the Spice Operating System. Servers are usually started by Accent when the 
machine is booted and continue running in the background for the complete session. 

A shell is a command interpreter program usually associated with a window, 
although not all windows need to have a shell. 'Hie shell also reads and edits (through 
the intra-line editing functions) the user's keyboard input before passing it along to 
the application program running on the window. The Shell command can be used to 
create a new window and to associate a shell with it. 



Spice partition 
Sys 



Tablet 



See partition. 

The device name for the local disk. It is the first component of a complete pathname 
within one Perq. To access files across the network, the "device name" to use is the 
name of the other machine. This "network name", the name by which a PliRQ is 
known throughout the network, is kept in a file (boot:SysName) in each machine. 

The tablet is the device which, in conjunction with the mouse, provides a mechanism 
to move the screen cursor around, and to select (i.e. point to) objects, windows, etc. 
on the screen. 



Tracker 



Typescript 



A process that keeps track (hence the name) of the position of the mouse on the 
tablet by moving some cursor or icon on the screen. 

A process that reads characters from the keyboard on behalf of the Shell and other 
programs. A Typescript process uses key translation files to interpret keyboard keys, 
some of which might be passed directly to the program, others could be translated 
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into some other characters before passing them to the program, and yet others could 
be used by Typescript as "commands" not to be passed to the program. The intra- 
line editing functions of the Shell arc implemented by a Typescript process. 



Virtual memory 



Window 



A technique by which the address space of a program can be made to appear much 
larger than the actual, physical memory in the computer. It is normally achieved by 
using disk storage as an extension to the physical memory. Under Accent, the paging 
partition is used to support the virtual memory of the server and user processes. 

A portion of the screen, usually associated with a shell or command interpreter. Any 
number of overlapping windows can be created but only one of them can be the 
current listener. 
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Appendix B 
Perq Hardware Configurations 

There are three types of Pi-rqs at CMU, PerqIA, Phrq2 and PkrqT2. PhrqIAs, the most common Perq 
type at CMU, have the following hardware features: 

• 16-bit micro-programmed processor; 

• 16K 48-bit words of writable control store; 

• high-resolution graphics using a L024 x 768 bit-mapped raster display; 

• 1- Mbyte of main memory; 

• 24-Mbyte Winchester-technology disk drive; 

• optional 1- (double-sided, double-density) floppy drive; 

• 3MHz or 10MHz Ethernet interface; 

• pointing tablet; 

• standard keyboard with special function keys; 

• RS232 & GPIB I/O interfaces; 

• audio (speech) output. 

The PERQ2 and PerqT2 have the Perq2 logo on the front of the main processor cabinet. The Piirq2 has an 
8", 40-Mbytc disk and two RS232 I/O interfaces. The PERQ17 has a 5.25" disk of various capacities and has 
the boot (Restart) button on front of the main processor cabinet. The PerqT2 is shorter and rounder than the 
Perq2. 

The PerqIA can be identified by the boot button at the rear of the keyboard. If you are updating to the S5 
system it is important to know if your PerqIA runs with the older version of die microcode, OIO, or the 
newer version, CIO. To distinguish what type of PerqIA you have: 

• If you are currendy using the S4 system, boot POS. Give the command 

Details /sys 
If the command does not exist, you are running OIO. 

• If you are currently running S5, type 

Details -io 
This command will tell you the type of PerqIA that you are using. 

The command to update a PerqIA with OIO is 
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Update Phrq1A_0I0 

and the command to update a PurqIA with CIO is 
Update PURQ1A_CI0 

Power consumption is roughly 700 W or 7A (it is. a non-resistive load); this is comparable to a home air 
conditioner. It may, therefore, be operated on a standard 15A branch circuit. Under current Duqucsne Light 
Company electric rates, the cost of using a Phrq at home is about $0.07/hour (ignoring slightly reduced home 
heating costs in winter and increased cooling costs in summer). Until availability, maintenance, and other 
issues arc resolved, however, home use is not being encouraged. It has been reported that many offices at 
CMU share 20A branch circuits; using more than three Phrqs at a time on such a circuit can trip the 
associated circuit-breaker. Caveat emptor! 
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Appendix C 
Booting Accent 

This appendix describes the booting sequence in full detail. Under normal conditions, you can safely ignore 
this material. Sometimes however, tilings do not seem to work as indicated in section 3.3. This material should 
be useful to identify the problem. 

If the Perq docs not boot properly (the Diagnostic Display docs not reach "400" or "450") and the material in 
this Appendix does not help to identify and correct the problem, please report the number displayed in the 
Diagnostic Display (DDS) (normally located on the underside of the keyboard on PkrqIAs; it is located on 
the front panel of the screen cabinet on Pf.rq2s and on the front of the main processor cabinet on PerqT2s). 

Assuming that the Perq is initially turned off, the following steps may be used to turn it on and bring up 
Accent: 

Power On 

Turn on the power by pushing the power on/off switch in the groove on the front panel of the main cabinet. 
The fans should start; if you do not hear them, check to see that the machine is plugged in. If so, see if the 
small neon light in the lower right hand side of the back of the cabinet is glowing. If the light is out 
(indicating lack of power on the line), check the electrical outlet. If there is power at the outlet or die light is 
glowing and you still do not hear the fans, send mail to Spicc@CMU-CS-Spice, specifying the symptoms and 
the location of die Perq. 

Boot Button 

After a few minutes, during which the disk is coming up to full speed, the Perq should automatically "boot" 
itself. Some Perqs, however, do not seem to do so. In that case, push the small red Boot button located at the 
rear of the keyboard (on Perq2s, this is a black button on the lower right hand side of the screen cabinet and 
on PerqT2s this is the Reset button on the front of the main processor cabinet). Many people regularly push 
the button after turning on the power. 

Diagnostic Micro-program 

While the machine is booting, a series of very regular patterns produced by the diagnostic microprogram 
called VFY will appear on the screen. They look like a set of binary trees, somewhat comb-like. 

Operating System Selection 

Just after the diagnostic microprogram finishes (the patterns disappear and you get a blank screen, with some 
horizontal retracing lines on it), the boot microcode decides what operating system to use by examining which 
key on the keyboard is pressed. Pressing none of the keyboard keys is equivalent to pressing (lowercase) "a", 
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which boots the standard Spice operating system. Accent. Other operating system/key combinations might be 
available on your Phrq (e.g., POS is normally asociated with the "b" key.) 

Because it may be hard to get the timing just right, a good mcdiod is to push the key down before pushing the 
boot button and then hold it (them) depressed until the operating system has announced itself. 

The bool selection key is read after the VFY has terminated and the DDS display shows "151" so in principle, you can wait 
until that point in the. booting sequence. Some users have learned to recognize the VFY screen patterns and wail until the 
right time before pressing the boot selection key. Until you get the hang of it, follow the instructions in the last paragraph. 

Life is not that easy however: pressing the boot selection key for too long has been know to screw up many Pmrq2s. If 
nothing seems to happen and the DPS display shows "152" you have one of these mutants. You will have to learn to 
release the boot selection key a couple of seconds after you see "151" come up on the DDS display. 

Setting the Clock 

After VFY has completed, the screen will become entirely white (with some bright, rolling, nearly-horizontal 
retrace lines crossing it) until Accent starts using the display. 

One of the first things Accent does after booting is to set its clock. It sends out a message on the Ethernet 

asking for the time. If it gets a response, it sets die clock and continues. If it gets no response (perhaps 

because the PERQ is not connected to the network), then it asks the user for the date and time, in the following 

format: 

Ol-Nov-83 14:04:00 Notice the format: this is a 24 hour clock 

Typing just RETURN will just, cause Accent to ask you again. 

Starting the Servers 

Accent will then start several "server" processes, and finally start Sapphire, the window manager program. 
Sapphire creates two windows on the screen, one near the top and one near the bottom. If this does not 
happen, or if the message "GPIB?" appears on die screen, it is possible that you tablet is not working 
properly. It definitively is not working if when you move the mouse, the cursor on the screen does not move. 

If you have a Perq with a large tablet and a puck, there arc several diings worth checking, each of which has 
caused problems in the past: 

• The puck was not placed on top of the tablet during the boot sequence. 

• The tablet's power supply, a large black box, might not be plugged in. 

• The cable from the power supply to the tablet may not be firmly plugged in to the back of the 
tablet. Note that this plug is polarized, so you need not worry about plugging it in upside down. 

• Either end of die GPIB cable from the Perq to the rear of die tablet might not be firmly 
connected (with its hold-down screws tight). 
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• Hie puck may not be plugged in to the front of the tablet. 

• The tablet might require reinitialization, which can be done by pressing the tablet-reset button on 
its right edge. In some extremes cases, it might be necessary to turn the Pi-rq off and then on 
again. 

If your Pi-RQ comes with a small tablet and a mouse, it could be the case that the tablet cord is not plugged 
into the display cabinet. 

After correcting any of these problems, it might be necessary to reboot. 
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Appendix D 
Notation Conventions 



Wc have attempted to use the following notations throughout this manual when describing the syntax of 
commands: 

SYMBOL MEANING 

used to separate alternatives 



I 
() 

[] 

{} 

Bold 

Italic 



CTRL 



ESC, INS 

DEL 

HELP 

LF 

RETURN 



used to indicate the scope of alternatives for | where it would not be otherwise 
obvious. 

used to enclose an optional feature, something that can appear or 1 times. 

used to enclose something that can appear or more times 

a literal, something that must be typed as it spells. 

a metaname, something that stands for a group or class of names. For instance, a file 
name can be described as: 

Name. Ext 

that is, a Name, followed by die literal ".", followed by an Ext. Name stands for any 
filename (i.e. a sequence of leters, digits, underscores, periods, and hyphens), not just 
IN a m e . 

used to prefix a control key (i.e. a key that must be typed while the keyboard 
"control" key is down). For instance, CTRL u indicates typing the 'control' and 'u' 
keys together. The keyboard control key acts like a conventional typewriter shift key. 
Nothing happens when it is typed or pressed by itself and you can keep it down while 
typing several CTRL keys in a row. 

the "escape" key (marked as ins on PerqIs and PERQlAs, and as ace esc on Perq2s). 

the "delete" key (marked as rej del on Perq2s). 

the "help" key (not the word "h" "e" "1" "p"). 

the line-feed key 

the carriage return key 



Because the documentation has been gathered from several distinct sources, we may not have been as 
successful as desired. Please report any discrepancies by mail to Spice@CMU-CS-Spice. 
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Appendix E 
Filename Extensions 

An extension is the portion of a filename that appears at the end, following the last period ("."). In Sesame, 
the Spice file system, there is nothing special about extensions. However, certain conventions arc used in the 
system and these arc described in this Appendix. 

Backup files conventionally have a "$" as the last character of their name; they take the form Name.KxtS. 
Some programs (e.g. Oil) make a copy of a file into a a backup version, with the same file name and extension 
(with die "$" at the end) before modifying a user's file. Oil also creates transcript files containing the Oil 
commands used while editing a file. These transcript files have "+" as a suffix to the original filename (i.e. 
Name.Ext+) 

A list of the standard extensions and how they are used follows. 

.ada This extension is used for SubAda source programs. 

.bin Micro-code object files. These files are produced by the micro-placer program, 

PrqPlace. 

.boot, .mboot The operating system and microcode interpreter files. 

.bsd Binary System Description, the file that Cousin accesses to get the definition of the 

form for each Cousin application, e.g. the form for CUpdate, the Cousin version of 
Update, is in CUpdate.bsd 

.c C source files. 

.ckp Temporary transcript files created by DP. 

.cpp,.i C prcproccssed (intermediate) files (during compilation). 

.cmd A number of programs accept commands from a file as well as from the keyboard. 

Files that contain the commands usually have this extension. Sec also .kmd, below. 

.dfs These files arg used to share definitions between Pascal and microcode programs. 

.defs These files contain definitions of server interfaces that are input to Matchmaker. 

.dp DP drawing files. 

.DR In the interim version of Sesame, directories are implemented as files. These files 

appear in a directory listing with a trailing "/" but are internally represented as 
having the extension .DR. Oniy users of POS should run into this extension; if it 
shows up anywhere else please send mail describing the situation to Spice@CMU- 
CS-Spice. 
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.exe C executable files. 

.h C include files, 

.help Files containing help about a subsystem use this extension. 

.lib C shared library files. 

.lmd C linker command files. 

.kcytran, .ktext Sapphire uses .keytran files to determine the mapping of keys on the keyboard and 
buttons on the mouse to "commands" for the servers, utilities, and user programs. 
.ktext files arc the "source" files used by the KeyTran compiler program 
KeyTranCom and .kcytran files are die "object" files produced by KeyTranCom. 

.kmd Kraut command files. 

.kst Character set definitions for use with the PURQ display screen are kept in files that 

have the extension .kst. 

■rn'om \Aif*rf\rr\Ao cnnrpp fi1f»c Thpc/s filAC ?irr» ncf»rJ ac innnf fr\ the* mirrn-nccnmhler PrnX/fir 

•mint,jnss Manuscript files, suitable for input to the document formatter, Mint, have this 

extension. 

.o C object files. 

.pas Pascal source files. 

.pasmac, .pm PasMac source files. Because filenames under Vax Unix must be fairly short, the 
extension .pm is sometimes used instead on that system. 

.press, .prt Formatted documents, suitable for printing on the Dover, have one of these 

extensions. The latter extension is used only for "temporary" press files that can be 
recreated easily and so can be deleted without much worry. 

.rcl, .rsym, .int These three file types are temporary files that are produced by the micro-assembler 
and the micro-placer programs. They can be deleted after a .bin file has been 
created. 

.run Runnable files produced by the Linker have this extension. 

.s C assembly code files. 

.sdo The Ascii, human readable version of Cousin's .bsd files. The application users don't 

need these, only the application builders. (It is an acronym for "self describing 
object"; this makes sense only for historical reasons.) 
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•scg Object code files produced by the Pascal and SubAda compilers, .seg files arc used 

as input to the Linker and. contain the code that will be executed when the program is 
run. 

.slisp, .sfasl Spice list source code and compiled code files, respectively. 

.sym, .qmap Files with these two extensions are created by the SubAda and Pascal compilers to 

pass information to the Kraut debugger. The .sym file contains the names of the 
variables and routines declared in the program; the .qmap file contains a mapping 
between Q-code offsets in the .scg file and corresponding source statements (in the 
.ada and .pas fiJcs). 
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Appendix F 
Predefined File Names 

In this Appendix we describe a few files whose names arc known to some programs (e.g. die Shell) and thus, 

have predefined meanings. Do not create files with these names for any purpose other than what is described 

below. " 

boot:SysName This file consists of a single line of text containing die "name" by which your machine will 
be known throughout the network. You arc free to edit this file and write any name you 
wish in the first line of the file (the first time you use the Pkrq, the file might not exist; you 
must create it with your favorite editor.) Common sense would seem to suggest that you 
use your last name (if this is truly a personal machine), an office number (if tliis machine is 
shared with officemates), or even a project name. Do not use "HarryQBovick" or "Sys" 
for obvious reasons. 

Do not edit this file without first checking with all the other users of the machine; they 
might count on it having a specific name. Never change tine name of a public machine. 

The name stored In SysName is registered in the Network when you boot the machine. If 
you just changed it, the new name will not be known until you re-booL 

boot:InitialShelI.cmd 

The Spice shell provides for user customization via command files. After booting, the shell 
looks for this file and then executes the commands contained in that file. Typically, this 
command file calls other command files diat define new commands and environment 
variables, set server priorities, and define logical names. This file is not for user commands. 

SysProfile This file is called by InitialShelLcmd. It contains general spice commands and is not for 

user commands. 

SiteProfiie This file is called by InitialShelLcmd. It contains CMU specific commands, definitions and 

variables. It is not for user commands. 

current:Shc!l Profile and currcntiShcllCommands 

These files are used to provide initial Shell commands, to be executed when a Shell is being 
created by Sapphire. 

To be precise, Shells created by Sapphire (typing CTRL del followed by s) inherit global 
environment variables and execute ShcllProfile and ShellCommands (in that order) if these 
files exist Shells created by executing die run file shell.s5.run, execute only the 
ShellProfile command file. Programs such as Make create shells with the shell.s5.run file. 
Shells created by the Shell command inherit the environment of the parent shell but do not 
execute any command files. 



UscrProfile This file is called by InitalShell.Cmd after SysProfile.Cmd and SiteProfile.Cmd. 

contains user commands such as launch and user definitions. 



It 
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Appendix G 
Son et Lumiere 

Accent does not provide much by way of audio entertainment, the visual amenities are however, worth a trip 
to die nearest operating Purq. 

At the top of the screen, above the Process Manager window, there arc a number of small (about 1x5 mm) 
rectangles. They arc called "lights" and arc used by Accent to indicate the state of the processor. If all lights 
arc off(whitc), the system is idle. r Hic meaning of each light, counting from the left, is as follows: 

1. (unused) 

2. DIRTY (currently rather meaningless; may be removed) 

3. IDLE 

4. MEMORY CLEANUP (no free pages; looking for unmapped pages) 

5. CREATE PHYSICAL SEGMENT 

6. NOT ENOUGH ROOM FOR PHYSICAL SEGMENT (error condition; failure in 5) 

7. FIND A FREE VP RECORD (same as 4 for VP pages) 

8. ALLOCATE A KERNEL AST BLOCK (probably unused) 

9. (unused) 

10. MSGS WAITING NON-NIL (File I/O in progress) 

11. (unused) 

12. (unused) 

13. FIND LEAST USED PAGE (when 4 doesn't find any free page) 

14. (unused) 

15. WRITE FAULT (Probably disabled) 

16. READ FAULT (Probably disabled) 

17. FINDINTREE (Probably disabled) 

18. PROCESS PAGE (Probably disabled) 

19. (unused) 

20. (unused) 

21. CREATE SHADOW SEGMENT 

22. (unused) 

23. DISK READ 

24. DISK WRITE 

25. (unused) 

26. (unused) 
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Appendix H 
Key Translation and the Intra-line Editor 

Some Spice programs such as DP, the Shell, Sapphire, and Oil bind certain character sequences typed from 
the keyboard to certain commands. This is accomplished by key translation files. A key translation file is a 
mapping of keys or key sequences typed into the keyboard to commands accepted by an application program. 
If you look for files with the extension .kcytran on the boot: partition, you will find various key translation 
files: The file oil.keytrah defines the keybindings for the OIL editor, dp.kcytran defines die keybindings for 
the DP drawing program, chat.keytraa defines die keybindings for the CHAT virtual terminal program, and 
the file boot:ts.keytran defines die commands understood by the intra-line editor in the shell. 

This appendix shows, by example, how to define a (new) key translation file for the intra-line editor. It is by 

r 

no means an introduction of how to create general key translation mappings or how they work internally. You 
must become a Sapphire expert in order to understand all the details. 

To define a new key translation file you have to start with a .ktext file. The .ktext file contains a description 
of the key translations in textual format, whereas the .keytran file contains them in a binary representation. 

A .ktext file consists of two parts: a command section and a keytranslation section. The command section 

contains a list of constant (number) declarations defining all the commands that can be bound to keys. Of 

course, they have to be known by the application, you cannot just make up your own constants. For example, 

the typescript process might equate the command cFDEL with the numeric value 54: cFDEL deletes the 

character next to the current cursor position. To make the command known in the key translation file, insert 
cFDEL = 54 ! Delete next character. 

in the command section of the .ktext file. Exclamation marks are regarded as the beginning of a comment 
Anything following a "!" up to the end of a line is regarded as comment. 

The kcvtranslation section binds keyboard keys or key sequences to the commands defined in the command 
section. Keys are in general denoted by their character prefixed by a quote (') or the string printed on the 
keyboard. Note that characters arc case sensitive. For example, 'a denotes the key lower case a and 'H the 
upper case H. BACKSPACE denotes the BACKSPACE key on the keyboard: The CTRL key is denoted by 
CONTROL and the space bar by SPACE. 

A simple key binding is 

CONTROL 'd = cFDEL 

which binds the key sequence CTRL d to the command cFDEL. 
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It is possible to bind sequences of keystrokes to commands. For example, 
CONTROL 'a + CONTROL 'b + CONTROL RETURN = cFDEL 

is a legal key binding: It binds the sequence CTRL a CTRL b CTRL rfturn to the command cFDEL. 

The following file contains all commands known to the typescript process and redefines them to a FLASH 
style instead of die default KM ACS style 4 . 

In the example, observe that the command section is prefixed by the words- DKFINITIONS and 
COMMAND, the key translation section is prefixed by the word KEYTRANSLATIONS. The file terminates 

with the word END. 

! Key translation file for the Typescript: Flash version 
DEFINITIONS 



COMMAND 




PosResponse 


= 40! 


cFIRST 


= 50! 


cLAST 


= 51! 


cNEXT 


= 52! 


cPREV 


= 53! 


cFDEL 


= 54! 


CBSP 


= 55! 


cEREOL 


= 56! 


CERBOL 


= 57! 


CTAB 


= 58! 


cTRANSP 


= 59! 


CRETURN 


= 60! 


CREDISP 


= 61! 


CDELNWD 


= 62! 


CDELPWD 


= 63! 


CNEXTWD 


= 64! 


cPREVWD 


= 65! 


CPREVPAG 


= 66! 


cNEXTPAG 


= 67! 


CUNBLOCK 


= 68! 


cSETMORE 


= 69! 


CDELMORE 


= 70! 


CUP 


= 71! 


CDOWN 


= 72! 


CLISTPATH 


= 73! 


cCOMPPATH 


= 74! 


cNOOP 


= 75! 


cILLEGAL 


= 76! 


cBELL 


= 77! 



Don't do anyting. 

Go to beginning of line. 

Go to end of line. 

Go to to next character. 

Go to previous character. 

Delete next character. 

Delete previous character. 

Delete to end of line. 

Delete to beginning of line. 

Insert a TAB. 

Twiddle the two before the current cursor. 

Insert a RETURN after the current cursor position, 

Redisplay the current listener window. 

Delete the next word. 

Delete the previous word. 

Move cursor back one word. 

Move cursor forward one word. 

Retrieve last command from command buffer 

Retrieve next command from command buffer 

?? 

Set current listener window into MORE mode. 

Set current listener window into SCROLL mode. 

Scroll up one page. 

Scroll down one page. 

List all files in current directory. 

Complete the file name or type all files with current prefix, 

Don't do anything. 

Illegal command. 

Ring the Bell . 



nng 
ring, 



FLASH is a text editor on Xerox's Alto personal computer. Some users prefer it over the standard Emacs-like shell intra-line editor. 
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KEYTRANSLATIONS 



Control 


'k 


= 


PosResponse 


! Make CTRL 


CONTROL 


•h 


= 


cFIRST 




CONTROL 


• ; 


= 


cLAST 




CONTROL 


'I 


= 


cNEXT 




CONTROL 


'J 


= 


cPREV 




CONTROL 


'd 


= 


cFDEL 




BACKSPACE 


= 


cBSP 




CONTROL 


'e 


= 


cEREOL 




CONTROL 


'E 


= 


cERBOL 




TAB 




= 


CTAB 




CONTROL 


't 


= 


CTRANSP 




RETURN 




= 


cRETURN 




CONTROL 


'# 


= 


cREDISP 




CONTROL 


' w 


= 


CDELNWD 




CONTROL 


'W 


= 


cDELPWD 




CONTROL 


'L 


= 


cNEXTWD 




CONTROL 


'J 


= 


cPREVWD 




CONTROL 


*n 


= 


CNEXTPAG 




CONTROL 


'y 


= 


cPREVPAG 




LF 




= 


cUNBLOCK 




CONTROL 


LF 


= 


CSETMORE 




CONTROL 


•\ 


= 


CDELMORE 




OOPS 




= 


cERBOL 




CONTROL 


' i 


= 


CUP 




CONTROL 


, 


= 


cDOWN 




CONTROL 


'? 


= 


cLISTPATH 




INS 




= 


CCOMPPATH 




CONTROL 


'g 


= 


CBELL 





K a NOOP 



END 



After you have created a file tsflash.ktext with the definitions above you want to create the corresponding 
.kcytran file. This is done by invoking the keytran compiler keytrancom which compiles the tsflash.ktext file 
into a binary tsfiash. kcytran file. 

If there are any errors in the .ktext file, the compiler suppresses the generation of the .kcytran file and writes 

error messages into the window and into a file with the extension .ERR. The keytran file will be created only 

if there are no serious errors. This is shown in the following dialog (User input is underlined): 
keytrancom ts. flash. ktext 
Key-Translation Compiler V2.1 

File with Keytran definitions (Ktext File): tsflash.ktext 

File for binary output [tsfiash. keytran]: tsfiash. KEYTRAN 

File for Pascal output [TsFlashKDefs.PAS]: TsFlashKDef s.PAS 

File for errors [TsFlash.ERR]: TsFlashKDef s. ERR 

* WARNING -- Command cNOOP defined but not used 

* WARNING -- Command cILLEGAL defined but not used 
Writing Defs file: tsflashKDef s.PAS 

Writing Keytran file: tsfiash. KEYTRAN 

There are 28 entries which take 106 words. 

Maximum hash chain length is 4 and there are 14 hash conflicts. 

** Reported 2 warnings. 

** These are all listed in file tsfiash. ERR 



To test the new kcytran file, copy it into boot:ts.kcytran file. The intra-linc editor commands of any new shell 
created afterwards will be bound according to the new key sequences. 
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